ReplaceIndexedCollectionItem

ReplaceIndexedCollectionItem
Header:	Collections.h		Carbon status:	Supported

Replaces the variable-length data of an item in a collection given the item’s index.

OSErr ReplaceIndexedCollectionItem (
    Collection c, 
    SInt32 index, 
    SInt32 itemSize, 
    const void *itemData
);

c: A reference to the collection containing the item you want to replace. The behavior of this function is undefined if you do not provide a reference to a valid collection object.
index: The collection index associated with the item to replace.
itemSize: The item’s size. The itemSize parameter determines how many bytes of information this function copies into the new item. If you specify 0 for this parameter, or provide NULL for the itemData parameter, this function copies no information into the variable-length data of the new item, or removes the variable-length data if the item already exists.
itemData: A pointer to the item’s data. This function copies the information pointed to by the itemData parameter into the new item; after calling this function, you may alter this information or free the memory pointed to by this parameter without affecting the collection.

function result: A result code.

DISCUSSION

You specify which item to replace using the index parameter. If the c collection does not contain an item whose collection index matches the value of the index parameter, this function returns a collectionIndexRangeErr result code.

If the c collection does contain an item with the specified index, this function replaces that item with a new item (if the existing item is not locked—if it is, this function returns a collectionItemLockedErr result code). The new item contains

the same collection tag as the original item
the same collection ID as the original item
the same attributes as the original item
the variable-length data specified by the itemSize and itemData parameters

To lock a collection item, use the functions SetCollectionItemInfo and SetIndexedCollectionItemInfo.

To replace a collection item using the item’s tag and ID (rather than the item’s index), use the ReplaceIndexedCollectionItemHdl function.

To remove an item from a collection, use the functions RemoveCollectionItem, RemoveIndexedCollectionItem, PurgeCollection, PurgeCollectionTag, and EmptyCollection.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.